━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ hs ファイル仕様書 Version 2.0 R2 update 2018/06/01 s.programs http://spn.php.xdomain.jp/ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ はじめに  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ このドキュメントは、HSP ヘルプマネージャ用のヘルプファイルである「hs ファイル」 の仕様を定義するものです。 改定履歴  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ 2004/04/07 (HSP HELP Browser 1.40 の実装) ・作成 2005/05/25 (HSP HELP Browser 1.50 の実装) ・行頭の特殊文字 '%', '^' のエスケープ仕様を追加 ・パラメータ書式の関数型表記仕様を追加 ・重複するシンボル名のリネームを廃止 2006/07/16 (hs ファイル仕様 Version 2.0) ・グローバルメンバ、ローカルメンバの区別を撤廃 ・新フィールドタグ %port, %portinfo に対応 ・差分記述の仕様を追加 ・行頭の特殊文字 '^' のエスケープ仕様の削除 ・容量制限の記述を削除 ・用語の一般化 - ページ → 「レコード」 - メンバ → 「フィールド」 - メンバ定義キーワード → 「フィールドタグ」 2018/06/01 Version 2.0 R2 ・解説文の表示フォント指定の削除 ・2005 年以前の「旧仕様」との互換にまつわる複雑な記載を削除 用語の定義  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ・hs ファイル ヘルプマネージャ用のヘルプ情報が格納されたテキストファイルを「hs ファイル」とい います。拡張子は hs です。文字コードは、Shift_JIS を用います。 ・レコード HSP で使われる特定のシンボル (命令など) について説明した、解説文やサンプルスクリ プトなどのデータ (フィールド) のひとまとまりをレコードと呼びます。ヘルプページの 1 ページが、1 レコードに当たります。hs ファイルには、一つ以上のレコードが含まれ ることになります。 ・フィールド フィールドとは、レコードに含まれる各要素のことです。命令名や見出し、解説文などが それに当たります。すべてのフィールドは文字列データとなっています。 ヘルプデータは、レコード×フィールドの、単純なカード型のデータベースとして扱われ ます。 基本書式  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ hs ファイル形式は、プレーンテキスト・データベースのヘルプ情報を記述するフォーマ ットです。基本的に、テキスト文章をファイルにそのまま記述していく形式となります。 レコードとフィールドを制御するために、文字 '%' で始まる「フィールドタグ」を使用 します。フィールドタグは、そのタグ以降に記述されるテキストがどのフィールド・レコ ードに属するかを宣言します。 フィールドタグには、下記の種類があります。 (タグ) (内容) ・%index シンボル名, 見出し ・%prm パラメータリスト, パラメータ説明文 ・%inst 解説文 ・%sample サンプルスクリプト ・%href 関連項目 ・%dll 使用プラグイン/モジュール ・%ver バージョン ・%date 日付 ・%author 著作者 ・%url 関連 URL ・%note 備考 (補足情報等) ・%type タイプ ・%group グループ ・%port 対応環境 ・%portinfo 移植のヒント フィールドタグは、行の頭に書く必要があります。大文字、小文字は区別されません。フ ィールドの値は、フィールドタグの次の行から、次のフィールドタグの前の行、もしくは ファイルの終了までに書かれたテキストデータとなります。フィールドタグは、どのよう な順番で記述してもかまいません。 %index は特に重要かつ特殊なタグで、フィールドの制御だけでなくレコードの区切りを 行う役目を持っています。一つのレコード内の情報は、%index から、次の %index もし くはファイルの終了までに書かれた値となります。よって、hs ファイルに含まれるレコ ードは、そのファイル内の %index の数だけ存在することになります。 また、ファイルの先頭から最初の %index までにフィールドタグで記述された値は、その hs ファイルのすべてのレコードのデフォルトの値となります。たとえば、最初の %index までに %port で対応環境を記述しておくと、その hs ファイルに含まれるレコードのう ち %port タグを含まないものは、すべて最初に記述された値が採用されます。明示的に 値が設定された場合は、そちらが優先されます。 hs ファイル中に不明なフィールドタグ (例 : %hoge) がある場合は、その中の値は無視 されます。また、ファイル先頭から最初のフィールドタグまでに含まれる文字列も同様に 無視されます。 ※ 説明文の中などで '%' で始まる行がある場合は、行頭を '%%' とすることでフィールド タグとして認識しないようにすることができます。 各フィールドの書式  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ 各フィールドの記述ルールの説明の前に、すべてのフィールドに共通のルールを説明しま す。 シンボル名 (%index) 以外のすべてのフィールドは省略可能です。記述が省略され、デフ ォルト値も記述されていないフィールドの値は、空になります。 文章の改行はビューアーの表示サイズに応じた自動折り返しとなりますので、文の途中で 改行を行わないで、段落ごとに改行を行うことを推奨します。また、英字、数字はなるべ く半角文字を使用することを推奨します。 各フィールド個別の記述ルールは、以下のようになります。 ◆ %index (シンボル名, 見出し) シンボル名と見出しを記述します。1 行目にシンボル名、2 行目に見出しを記述してくだ さい。このフィールドタグが、レコードの記述の開始地点となります。シンボル名の省略 はできません。 見出しは、シンボルの機能を簡潔に表した、なるべく短いものにしてください。見出しに は改行は使えません。 ◆ %prm (パラメータリスト, パラメータ説明文) 命令やマクロのパラメータを記述します。1 行目にパラメータリスト (パラメータ書式)、 2 行目以降は各パラメータの概要を記述してください。 パラメータを持たないシンボルの場合は、"パラメータ無し" 等と書かないで、フィール ドタグの記述を省略してください。また、パラメータを関数式記述にする場合は、パラメ ータリストを括弧 ( ) で囲んでください。 ◆ %inst (解説文) 解説文を記述します。この部分がヘルプページのメインとなります。 ◆ %sample (サンプルスクリプト) サンプルスクリプトを記述します。 行の 1 文字目がセミコロン ';' の場合、hs ファイルのコメントとして扱われ、行が無 視されますので注意してください。 ◆ %href (関連項目) 関連するシンボルを、改行区切りで記述します。 ◆ %dll (使用プラグイン/モジュール) 使用するプラグインやモジュールがある場合、その名称を記述します。一行のみ書くこと ができます。 HSP 標準機能でないヘルプでは、この記述は省略できません。DLL を使用しないモジュー ルであっても、モジュールファイル名などを記述する必要があります。 ◆ %ver (バージョン) バージョンを記述します。一行のみ書くことができます。 ◆ %date (日付) 日付を記述します。更新履歴などのために必要であれば、複数行にわたって書くことがで きます。 ◆ %author (著作者) 著作者名を記述します。連名にする場合は、複数行で書きます。 ◆ %url (関連 URL) 関連する URL を記述します。複数の URL を記述する場合は、複数行にします。 ◆ %note (備考) 備考や注意書きがあれば記述します。複数行にわたって記述できます。 ◆ %type (タイプ) シンボルのタイプを記述します。記述例は "拡張命令", "ユーザー拡張命令" などです。 一行のみ書くことができます。 ◆ %group (グループ) 機能を分類するグループを記述します。記述例は、"画面制御命令", "文字列操作命令", "入出力制御命令" などです。一行のみ書くことができます。 ◆ %port (対応環境) どのプラットフォームの HSP 実行環境に対応するかを表すフラグ文字列を記述します。 フラグ文字列は、大文字、小文字まで正確に記述してください。複数のプラットフォーム で実行できる場合、複数行に分けて書きます。現在決まっているフラグは、下記のものが あります。 (フラグ) (環境) ・Win Windows 版 HSP ・Mac Macintosh 版 HSP ・Let HSPLet ・Cli コマンドライン版 HSP ◆ %portinfo (移植のヒント) プラットフォーム間の移植についてのヒントを記述します。 フィールドの差分記述  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ 下記のフィールドタグは、(最初の %index までに書かれる) デフォルト値に対する差分 の記述をサポートします。 ・%port+ 対応環境フラグへ追加 ・%port- 対応環境フラグから除外 たとえば、下記のような hs ファイル記述がある場合、 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - %port ; デフォルト Win Let %index test1 %port+ ; 差分 (追加) Mac %index test2 %port- ; 差分 (除外) Let - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - シンボル test1 の %port フィールドの値は、デフォルト値に Mac を追加した 3 行とな り、test2 の %port フィールドの値は、デフォルト値から Let を除外した 1 行となり ます。 一つのレコードで %port+ と %port- を両方記述することもできます。また、追加時に、 すでに含まれるフラグは重複しての追加はされません。 コメントについて  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ セミコロン文字 ';' で始まる行はコメントとみなされ、無視されます。また、'%' で始 まるタグ行では、タグ文字列以降の ';' からコメントとして扱われます。 (コメントの例) ; -------- comment %index ; -------- comment 特にサンプルスクリプト中でスクリプトのコメント用に ';' を使う場合は、それを行頭 に書かないように注意してください。';' の前にスペースやタブがある場合はコメントと みなされません。 タグ ( ^ ) の扱い  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ "^" もしくは "^p" とだけ書かれている行は、空行として処理されます。 hs ファイルの記述例  ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ̄ ;--------------------------------------------------------------- ; hs ファイル サンプル ; (hs specification version 2.0) ;--------------------------------------------------------------- %dll ; モジュールの名前 hhx_db.hsp %ver 2.0 %date 2006/07/16 %author sprocket %url http://spn.php.xdomain.jp/ %note hhx_db.hsp をインクルードすること。 %type ユーザー拡張命令 %group hs データベース処理 %port Win ; ここまでに定義されたフィールドの値が、以降のレコードのデフォルト値となります。 %index HHX_init_load_db hs データベースをロード %inst カレントディレクトリにある hs データベースファイル (hhx.db) をロードします。この 命令が成功した場合、システム変数 stat に 0 が返ります。 hs ファイルが更新されている場合や、hhx.db が存在しない場合は、stat に 1 が返りま す。その場合は、HHX_init_rebuild_db 命令で hhx.db を再構成してください。 HHX_init_load_db, HHX_init_rebuild_db の実行後には、HHX_init_extract_db 命令でロ ードしたデータベースをメモリ上に展開する必要があります。 %sample #include "hhx_db.hsp" ; HHX データベース ロードシーケンス mes "loading..." HHX_init_load_db if stat { mes "rebuilding db..." HHX_init_rebuild_db } HHX_init_extract_db mes "complete." %href HHX_init_rebuild_db HHX_init_extract_db [EOF]